Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 4 - Dialog Manager Reference / Dialog Manager Functions

Creating Alerts /

Alert

CHANGED WITH THE APPEARANCE MANAGER

Displays an alert box (or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box).

pascal short Alert  (short alertID,
                     ModalFilterUPP modalFilter);

alertID

The resource ID of an alert resource and extended alert resource. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert.

modalFilter

A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to nil, the Dialog Manager uses the standard event filter function.

function result

If no alert box is to be drawn at the current alert stage or the 'ALRT' resource is not found, Alert returns -1; otherwise, it creates and displays the alert box and returns the item number of the control selected by the user; see "Alert Button Constants".

DISCUSSION

The Alert function creates the alert defined in the specified alert resource and its corresponding extended alert resource. The function calls the current alert sound function and passes it the sound number specified in the alert resource for the current alert stage. If no alert box is to be drawn at this stage, Alert returns -1; otherwise, it uses the NewDialog function to create and display the alert box. The default system window colors are used unless your application provides an alert color table resource with the same resource ID as the alert resource. The Alert function uses the ModalDialog function to get and handle most events for you.

The Alert function does not display a default icon in the upper-left corner of the alert box; you can leave this area blank, or you can specify your own icon in the alert's item list resource, which in turn is specified in the alert resource.

The Alert function continues calling ModalDialog until the user selects an enabled control (typically a button), at which time the Alert function removes the alert box from the screen and returns the item number of the selected control. Your application then responds as appropriate when the user clicks this item.

IMPORTANT

Your application should never draw its own default rings. Prior to Mac OS 8, the Alert function would only redraw the default button ring once and never redraw it on an update event. However, when Appearance is available, default rings do redraw when you call Alert.

SPECIAL CONSIDERATIONS

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser; see Inside Macintosh: Interapplication Communication.

The Dialog Manager uses the system alert sound as the error sound unless you change it by calling the ErrorSound function .

SEE ALSO

NoteAlert.

CautionAlert.

StopAlert.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

Alert only reads in the resource ID of an alert resource, not an extended alert resource.